Version: 1.3.2

Chat API

title: Chat

description: Comprehensive documentation for the Chat Service.

Chat API Documentation

Chat Retrieval Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/
Summary: Retrieves chat history for a specific bot with optional filtering and pagination.

Description

Retrieves chat history for a specific bot with optional filtering and pagination.

Request

Content-Type: application/json

Query Parameters

Name	Type	Description	Constraints	Required
chat_bot_id	UUID	Chatbot identifier	-	Yes
page_no	number	Page number	Min: 1	No
page_size	number	Records per page	Min: 1	No
order	string	Sort order	"asc" or "desc"	No
exclude_tool_verbose	bool	Filter tool and verbose history	True or False	No

Payload (Body)

Field	Type	Description	Constraints
text	string	Search text in queries/responses	Optional
created_by	string	Filter by user ID	Optional, Valid user ID

Response

Success (200 OK)

{
  "status_code": 200,
  "message": "Chat history fetched successfully",
  "total_count": 1,
  "data": {
    "has_continuations": false,
    "chat_hist": [
      {
        "_id": "string",              // MongoDB ObjectId
        "tenant_id": "string",        // UUID
        "user_id": "string",
        "object_id": "string?",
        "user_query": "string",
        "bot_response": "string",
        "chat_bot_id": "string",      // UUID
        "user_type": "internal|external",
        "is_cleared": 0,
        "creation_time": "2025-12-22T12:37:42.985Z",
        "response_time": "2025-12-22T12:37:43.000Z",
        "metadata": {
          "category": "chat"
        },
        "is_positive": true,
        "query_response_id": "string",
        "chat_bot_name": "string"
      }
    ]
  }
}

Other Responses

No Records Found Response

{
  "status_code": 404,
  "message": "No chat record found",
  "total_count": 0,
  "data": {
    "has_continuations": false,
    "chat_hist": []
  }
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "chat_bot_id": "bot-uuid-here",
    "page_no": 1,
    "page_size": 10,
    "order": "asc"
}

data = {
    "text": "search query",
    "created_by": "user123"
}

response = requests.post(url, headers=headers, params=params, json=data)

if response.status_code == 200:
    print("Chat History:", response.json())
else:
    print("Error:", response.status_code, response.text)

Chat Download Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/download/

Description

Downloads chat history as a PDF file for a specific bot. Returns a URL to access the generated PDF.

Request

Content-Type: application/json

Name	Description	Type	Constraints
chat_bot_id	Chatbot identifier	UUID
object_id	Associated object identifier	string	Max length: 100
ext_ref_user_id	External reference user ID	string	Max length: 100
text	Search text in queries/responses	string	Max length: 500
created_by	Filter by user ID	string	Valid user ID

Response

Success Response

{
  "message": "PDF uploaded to S3 successfully",
  "file_url": "https://kadal.ai/chat_history/{tenant_id}/{filename}"
}

Other Responses

{
  "status_code": 404,
  "message": "No chat record found",
  "total_count": 0,
  "data": {
    "has_continuations": false,
    "chat_hist": []
  }
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/download/"
token = "token-here"


headers = {
    "Origin": "https://kadal.ai",
    "Authorization": f"Bearer {token}"
}

query_params = {
    "chat_bot_id": "bot-uuid-here"
}

response = requests.post(url, headers=headers, params=query_params)

if response.status_code == 200:
    print("Download URL:", response.json())
else:
    print("Error:", response.status_code, response.text)

Chat Clear History Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/clearhistory

Description

Clears chat history for a specific bot with optional filtering.

Request

Content-Type: application/json

Parameters

Name	Type	Required	Description	Constraints
chat_bot_id	UUID	Yes	Chatbot identifier	Valid UUID format
object_id	string	No	Associated object identifier	Max length: 100
ext_ref_user_id	string	No	External reference user ID	Max length: 100

Response

Success Response

{
  "status_code": 200,
  "message": "Previous conversations deleted successfully",
  "query_response_id": null,
  "finish_reason": ""
}

Other Responses

{
  "status_code": 404,
  "message": "Agent wasn't found.",
  "query_response_id": "",
  "finish_reason": "no_bot_found"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/clearhistory"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "chat_bot_id": "bot-uuid-here",
    "object_id": "obj123",
    "ext_ref_user_id": "user123"
}

response = requests.post(url, headers=headers, params=params)

if response.status_code == 200:
    print("History cleared:", response.json())
else:
    print("Error:", response.status_code, response.text)

Stream Chat Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/{chat_bot_id}/stream

Description

Streams chat responses with support for file handling and tool configurations.

Request

Content-Type: application/json
Path Parameter
Name Description Type Constraints Required
chat_bot_id Chatbot identifier UUID - Yes

Name	Description	Type	Constraints	Required
chat_bot_id	Chatbot identifier	UUID	-	Yes

Query Parameter

Name	Description	Type	Constraints	Required
stream	Enable token-by-token streaming	boolean	Default: false	No
continue_last_chat	Continue previous context	boolean	Default: false	No
object_id	Associated object identifier	string	Default: null	No

Image Generation Payload

To generate an image, follow these two steps:

1. Set up tool configuration:

Send this payload to configure the tool for image generation:

{
  "message": "#ToolCalling$",
  "metadata": {
    "category": "event",
    "type": "tool",
    "message": "web search disabled and content lake disabled",
    "tool_config": {
      "content_lake": false,
      "web_search": false,
      "image_generation": true
    },
    "tool_settings": {
      "image_generation": {
        "model_provider": "VertexAI",
        "model_version": "imagen-3.0-fast-generate-001",
        "aspect_ratio": "AUTO",
        "num_images": "1"
      }
    }
  }
}

2. Request image generation:

After configuring, send a prompt to generate the image:

{
  "message": "Generate an image of a flower",
  "metadata": {
    "category": "chat"
  }
}

Payload

{
  "message": "string",
  "is_tool_calling": false,
  "metadata": {
    "category": "chat"  // See metadata types below
  }
}

Metadata Types

Basic Chat

{
  "category": "chat"
}

File Processing

{
  "category": "event",
  "type": "file",
  "files": [{
    "file_name": "string",
    "file_type": "string",
    "object_id": "string?",
    "folder_id": "string?",
    "source_category": "InputFile|ContextFile|KnowledgeBase|Guideline|OutputTemplate",
    "input_type": "Repository|Computer|GDrive",
    "url": "string"
  }]
}

Tool Configuration

{
  "category": "event",
  "type": "tool",
  "message": "string",
  "tool_config": {
    "web_search": "boolean",
    "content_lake": "boolean"
  }
}

Model Switch

  "metadata": {
    "category": "event",
    "type": "verbose",
    "message": "string",
    "modelId" : "string",
    "modelVersion": "string"
}

Response

Non-streaming Response (application/x-ndjson)

{"status_code":200,"message":"Response message","session_id":null,"query_response_id":"68ac044e3b3b0e000a5a7dc8","finish_reason":"stop"}

Streaming Response (application/x-ndjson)

{"status_code":200,"message":"The","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" phrase","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" \"","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"Mary","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" had","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" a","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" little","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" lamb","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"\"","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" contains","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" ","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"5","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" words","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":".","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"#","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"stop"}

Other Responses

{
  "status_code": 200,
  "message": "The context is too lengthy for effective processing. Please revise your templates, guidelines, or instructions to make them more concise, or upload a smaller file.",
  "finish_reason": "input_exceeded_context_window"
}

Safety Guardrail Hit

{
  "status_code": 200,
  "message": "Sorry, the model cannot answer this question due to harmful or sensitive information. This will be recorded as a violation, and your administrator will be notified.",
  "finish_reason": "guardrail_hit"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/{chat_bot_id}/stream"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "stream": True,
    "continue_last_chat": False
}

data = {
    "message": "Hello",
    "is_tool_calling": False,
    "metadata": {
        "category": "chat"
    }
}

response = requests.post(url, headers=headers, params=params, json=data, stream=True)

for line in response.iter_lines():
    if line:
        print(line.decode())

Chat Feedback Endpoint

Description

Submits feedback for chat interactions with optional metadata and details.

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v3/feedbacks

Request

Content-Type: application/json

Payload

Name	Description	Type	Constraints	Required
chatbotId	Bot identifier	string	UUID format	No
consumerId	Consumer ID	integer	-	No
keycloakConsumerId	Keycloak consumer ID	string	UUID format	No
tenantId	Tenant ID	integer	-	No
keycloakTenantId	Keycloak tenant ID	string	UUID format	No
reason	Feedback reason	string	One of ["pre-defined", "other"]	No
details	Detailed feedback	string	Max length: 1000	No
user_query_id	Query ID	integer	-	No
query	Original user query	string	Max length: 500	No
metadata	Additional metadata	object	-	No

{
  "chatbotId": "string?",              // UUID format
  "consumerId": "number?",             // Integer
  "keycloakConsumerId": "string?",     // UUID format
  "tenantId": "number?",               // Integer
  "keycloakTenantId": "string?",       // UUID format
  "reason": "string?",                 // Pre-defined or custom
  "details": "string?",                // Detailed feedback
  "user_query_id": "number?",          // Integer
  "query": "string?",                  // Original user query
  "metadata": {                        // Optional metadata
    "source": "string?",
    "version": "string?"
  }
}

Response

Success Response

{
  "status": "success",
  "message": "Feedback submitted successfully",
  "document_id": "67eba353969855dc98a85e37"
}

Other Responses

{
  "status_code": 400,
  "message": "Invalid request format",
  "error": "VALIDATION_ERROR"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v3/feedbacks"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "chatbotId": "550e8400-e29b-41d4-a716-446655440000",
    "consumerId": 8,
    "reason": "pre-defined",
    "details": "Not factually correct",
    "query": "What are the main features?",
    "metadata": {
        "source": "web",
        "version": "1.0.2"
    }
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 201:
    print("Feedback submitted:", response.json())
else:
    print("Error:", response.status_code, response.text)

Create chat parameters Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v1/chat_params/create
Summary: Create chat parameters

Description

Create chat parameters

Request

Content-Type: application/json

Payload

Field	Type	Description	Validation
session_id	string	Unique identifier for the chat session	UUID format
chat_bot_id	string	Identifier for the chatbot instance	UUID format
object_id	string	Identifier for the related object	UUID format
memory	boolean	Flag to enable memory for the session	Required (true/false)
full_memory	boolean	Flag to enable full memory capture	Required (true/false)
memory_size	number	Maximum number of memory entries retained	Integer, Required
memory_content	array	List of memory entries	Array of strings, Optional
summary	string	Summary of the session	Optional
uploaded_files	array	List of uploaded files	Optional
uploaded_files.object_id	string	Identifier for the uploaded file	UUID format
uploaded_files.file_name	string	Name of the uploaded file	Required
uploaded_files.file_type	string	Type of the uploaded file (e.g., pdf, docx)	Required
uploaded_files.url	string	URL to access the uploaded file	Valid URL
uploaded_files.status	string	Status of the file (e.g., NA, Active)	Enum: NA/Active/Failed
uploaded_files.input_type	string	Source type of the file (e.g., Repository)	Enum: Repository/Manual/Other
uploaded_files.meta	object	Metadata about the file	Required
uploaded_files.meta.size_bytes	number	File size in bytes	Integer, â‰¥ 0
uploaded_files.meta.size_token	number	Tokenized size of the file	Integer, â‰¥ 0
uploaded_files.meta.uploaded_at	string	Timestamp when file was uploaded	ISO 8601 datetime
uploaded_files.meta.updated_at	string	Timestamp when file was last updated	ISO 8601 datetime

Response

{
  "message": "Chat parameters created successfully",
  "id(s)": "69493d1cfb177dea15bd233c"
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/aiwb/chat/api/v1/chat_params/create"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

data = {
  "session_id": "string",
  "chat_bot_id": "string",
  "object_id": "string",
  "memory": true,
  "full_memory": false,
  "memory_size": 5,
  "memory_content": [
    "string"
  ],
  "summary": "string",
  "uploaded_files": [
    {
      "object_id": "string",
      "file_name": "string",
      "file_type": "string",
      "url": "string",
      "status": "NA",
      "input_type": "Repository",
      "meta": {
        "size_bytes": 0,
        "size_token": 0,
        "uploaded_at": "2025-12-22T12:37:42.985Z",
        "updated_at": "2025-12-22T12:37:42.985Z"
      }
    }
  ]
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Get chat parameters Endpoint

Method: GET
Path: https://api.kadal.ai/aiwb/chat/api/v1/chat_params/get
Summary: Retrieve chat session parameters for a specific session, chatbot, and object.

Description

This endpoint fetches the configuration and state parameters for a chat session, including memory settings, uploaded files, and session metadata. It is useful for restoring or inspecting the state of a chat session.

Authentication

Type: Bearer Token (JWT)
Header: Authorization: Bearer <token>

Request

Content-Type: application/json

Payload

Field	Type	Description	Validation	Required
session_id	string	Unique identifier for the session	UUID format	Yes
chat_bot_id	string	Identifier for the chatbot instance	UUID format	Yes
object_id	string	Identifier for the related object	UUID format	Yes

Example Request

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v1/chat_params/get?session_id=<session_id>&chat_bot_id=<chat_bot_id>&object_id=<object_id>"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Example Success Response

{
  "_id": "69394b61d49a7ad5732881ec",
  "tenant_id": "8cfc8013-eb69-44ff-8dde-34b7699b3f37",
  "user_id": "75fff633-7eba-45b8-9277-b400c462c807",
  "session_id": null,
  "chat_bot_id": "ae3603cf-0a99-47fb-8888-41e88ef66488",
  "object_id": null,
  "memory": true,
  "full_memory": false,
  "memory_size": 5,
  "memory_content": [],
  "summary": "",
  "uploaded_files": [
    {
      "object_id": "6c15c4e1-00a5-42ea-9732-6a7089e816e5",
      "file_name": "Krebs_Cycle.txt",
      "file_type": "txt",
      "url": "https://kadal.ai/assets/8cfc8013-eb69-44ff-8dde-34b7699b3f37/6c15c4e1-00a5-42ea-9732-6a7089e816e5/2895c9a8-08a7-4161-a441-9439f54249c7/Krebs_Cycle.txt",
      "status": "pinned",
      "input_type": "Repository",
      "meta": {
        "size_bytes": null,
        "size_token": null,
        "uploaded_at": "2025-12-10T10:36:56",
        "updated_at": [
          "2025-12-23T07:31:52"
        ]
      }
    }
  ]
}

Error Responses

400 Bad Request:

Missing or invalid query parameters.

Example:

{
  "status_code": 400,
  "message": "Invalid session_id format"
}

401 Unauthorized:
- Missing or invalid authentication token.
- Example:
```
{
  "status_code": 401,
  "message": "Unauthorized"
}
```
404 Not Found:
- No chat parameters found for the given identifiers.
- Example:
```
{
  "status_code": 404,
  "message": "No chat parameters found"
}
```

Notes

All query parameters are required and must be valid UUIDs.
The endpoint does not require a request body.
Use this endpoint to restore chat state or debug session issues.

Update chat parameters Endpoint

Method: PUT
Path: https://api.kadal.ai/aiwb/chat/api/v1/chat_params/update?session_id=<session_id>&chat_bot_id=<chat_bot_id>&object_id=<object_id>
Summary: Update or modify chat session parameters, including memory settings and file management, for a specific session, chatbot, and object.

Description

This endpoint allows you to update the configuration and state of a chat session. You can enable/disable memory, adjust memory size, pin or unpin files, and delete files associated with the session. This is useful for managing session state, memory optimization, and file organization.

Authentication

Type: Bearer Token
Header: Authorization: Bearer <token>

Request

Content-Type: application/json

Payload

Field	Type	Description	Validation	Field Type
memory	boolean	Flag to enable memory for the session	Required (true/false)	request body
full_memory	boolean	Flag to enable full memory capture	Required (true/false)	request body
memory_size	number	Maximum number of memory entries retained	Integer, â‰¥ 0	request body
pinned_files	array	List of pinned files	Optional	request body
pinned_files.object_id	string	Identifier for the pinned file	UUID format, Required	request body
pinned_files.status	string	Status of the pinned file	Enum: pinned/unpinned/NA	request body
delete_files	array	List of file identifiers to delete	Each item UUID, Optional	request body

Example Request

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v1/chat_params/update?session_id=<session_id>&chat_bot_id=<chat_bot_id>&object_id=<object_id>"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
  "memory": true,
  "full_memory": true,
  "memory_size": 10,
  "pinned_files": [
    {
      "object_id": "b1e2c3d4-5678-1234-9abc-def012345678",
      "status": "pinned"
    }
  ],
  "delete_files": [
    "c3d4e5f6-7890-3456-9cde-f23456789012"
  ]
}

response = requests.put(url, headers=headers, json=data)

if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Example Success Response

{
  "message": "Chat parameters updated successfully"
}

Error Responses

400 Bad Request:
- Missing or invalid parameters in query or body.
- Example:
```
{
  "status_code": 400,
  "message": "Invalid memory_size value"
}
```
401 Unauthorized:
- Missing or invalid authentication token.
- Example:
```
{
  "status_code": 401,
  "message": "Unauthorized"
}
```
404 Not Found:
- No session found for the given identifiers.
- Example:
```
{
  "status_code": 404,
  "message": "Session not found"
}
```

description: Comprehensive documentation for the Chat Service.​

Chat API Documentation

Chat Retrieval Endpoint​

Description​

Request​

Query Parameters​

Payload (Body)​

Response​

Success (200 OK)​

Other Responses​

No Records Found Response​

Usage​

Chat Download Endpoint​

Description​

Request​

Response​

Success Response​

Other Responses​

Usage​

Chat Clear History Endpoint​

Description​

Request​

Parameters​

Response​

Success Response​

Other Responses​

Usage​

Stream Chat Endpoint​

Description​

Request​

Path Parameter​

Query Parameter​

Image Generation Payload​

Payload​

Metadata Types​

Response​

Non-streaming Response (application/x-ndjson)​

Streaming Response (application/x-ndjson)​

Other Responses​

Safety Guardrail Hit​

Usage​

Chat Feedback Endpoint​

Description​

Request​

Payload​

Response​

Success Response​

Other Responses​

Usage​

Create chat parameters Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Get chat parameters Endpoint​

Description​

Authentication​

Request​

Payload​

Example Request​

Example Success Response​

Error Responses​

Notes​

Update chat parameters Endpoint​

Description​

Authentication​

Request​

Payload​

Example Request​

Example Success Response​

Error Responses​

description: Comprehensive documentation for the Chat Service.

Chat Retrieval Endpoint

Description

Request

Query Parameters

Payload (Body)

Response

Success (200 OK)

Other Responses

No Records Found Response

Usage

Chat Download Endpoint

Description

Request

Response

Success Response

Other Responses

Usage

Chat Clear History Endpoint

Description

Request

Parameters

Response

Success Response

Other Responses

Usage

Stream Chat Endpoint

Description

Request

Path Parameter

Query Parameter

Image Generation Payload

Payload

Metadata Types

Response

Non-streaming Response (application/x-ndjson)

Streaming Response (application/x-ndjson)

Other Responses

Safety Guardrail Hit

Usage

Chat Feedback Endpoint

Description

Request

Payload

Response

Success Response

Other Responses

Usage

Create chat parameters Endpoint

Description

Request

Payload

Response

Usage

Get chat parameters Endpoint

Description

Authentication

Request

Payload

Example Request

Example Success Response

Error Responses

Notes

Update chat parameters Endpoint

Description

Authentication

Request

Payload

Example Request

Example Success Response

Error Responses